現在有了 Claude Code、Codex、OpenCode、Pi 這類 coding agents，要在短時間內做出一個可以執行的 application 已經比以前容易很多。

這大幅降低了從 idea 到落地的成本，也讓開發速度變得非常快。

但開發變快，不代表 software engineering 就不重要了。

當 application 越來越大，如果我們不了解原本的 codebase design，就很容易在加入新功能時造成 regression、重複邏輯，或是不必要的 coupling。

Coding agent 的確可以很快產生 code，但如果 codebase 本身很難理解，最後不管是人還是 Agent，都會越來越難加新的功能或維護他。

換句話說：

AI 可以讓 implementation 變快，但好的 system design 與 codebase design，仍然決定了這個 application 未來能不能持續演進。

今天這一篇會先把開發環境建起來，也會簡單介紹這個系列中會使用到的 coding agents 和一些我自己在用的skill。

如果你已經有自己習慣的 development environment 和 coding-agent workflow，這一篇大部分內容都可以直接跳過。

Tools

IDE

這個系列主要會使用 Visual Studio Code。

不一定要使用 VScode，只要你使用的 IDE 或 editor 能夠順利搭配 coding agent 就可以，用他只是我的個人習慣。

Coding Agent

Coding agent 會大量參與這個 project 的開發，不一定要使用跟我一樣的，選擇自己順手的就可以了。

下面是幾個可以選擇的工具。

Claude Code

Claude Code 可以透過 npm 安裝：

npm install -g @anthropic-ai/claude-code

接著在 project directory 中執行：

claude

也可以執行：

claude doctor

來檢查 installation 與 environment 是否正常。

Official setup guide: Claude Code — Getting Started

Claude Code 會是這個系列主要使用的 coding agent。

Codex

Codex CLI 可以透過 npm 安裝：

npm install -g @openai/codex

接著進行登入：

codex --login

完成後，就可以直接在 project directory 裡啟動：

codex

Official guide: OpenAI Codex CLI — Getting Started

這個系列中也會偶爾使用 Codex。

OpenCode

OpenCode 可以使用：

curl -fsSL https://opencode.ai/v2/install | bash

或是透過 npm：

npm install -g @opencode/cli

接著執行：

opencode

Official documentation: OpenCode Docs

如果你偏好更 configurable、比較自由的環境設定，OpenCode 會是一個不錯的選擇。

Pi

Pi 可以透過 npm 安裝：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

接著在 project directory 中啟動：

pi

根據你使用的 provider，可以透過 /login 或 API key 設定 authentication。

Official quickstart: Pi Quickstart

Pi 是相對 minimal 的 coding-agent harness，如果你希望對 extensions、skills，以及整體 workflow 有更多控制，它會是一個很有趣的選擇。

要跟著這個系列做，其實只需要 一個 coding agent 就可以。

比起使用哪一個工具，更重要的是你怎麼和它合作。

後面我們會再看到，要怎麼提供 coding agent 足夠的 context、constraints 和 project structure，讓它可以幫忙快速修改 code，同時又不會讓 codebase 隨著時間變得越來越難維護。

Skills I Used

我也有使用一些 reusable skills，讓和 coding agent 的互動更有結構。

其中有幾個 templates 是參考 AI Hero Skills：

• tdd — 引導 coding agent 使用 test-first workflow 開發功能。
• grill-me — 在開始 implementation 之前，透過一連串問題把模糊的想法釐清。
• to-spec — 把討論過程中的決策整理成具體的 specification，方便後續 implementation。
• handoff — 把目前工作的 context 整理好，讓下一個 session 或 agent 可以直接接著做。
• wait-what — 當前面的解釋太複雜或不夠清楚時，讓 agent 用更簡單、容易理解的方式重新說明。(我很喜歡用這個，特別是在狀態不好的時候Claude的output很難吸收)

安裝畫面大概像這樣：

不過沒有這些 skills 也完全沒問題，它們比較像是一些小幫手，讓使用者可以更有效率的使用他。

Environment

這個 project 的環境建置可以分成三個部分：

1. Backend
2. Frontend
3. Sandbox / execution environment

目前我們只會先建立 backend 和 frontend。

Sandbox 會在後面開始執行 Agent-generated analysis code 時再介紹。

Backend

Backend 會使用 Python。

Python environment 和 dependency management 會使用 uv。

uv 是一個速度很快的 Python package / project management tool，可以一起處理 virtual environment 和 dependencies。

基本 setup 如下。

Initialize the Project

先進入 backend directory：

uv init

這會初始化一個 Python project，並產生基本的 project files。

Create the Virtual Environment

這個系列會使用 Python 3.13：

uv venv --python 3.13

這會建立 project 使用的 virtual environment。

Add Dependencies

要加入 package，可以使用：

uv add <package_name>

例如：

uv add langchain
uv add deepagents

之後開始打造 Agent 時，就會使用到這類 package。

使用 project-level dependency manager 的其中一個好處，是 environment 比較容易重現。

我們不需要每個人各自手動安裝 package，再期待大家剛好使用相同版本，而是可以把 project 所需要的 dependencies 明確定義下來。

Frontend

Frontend 會使用：

• React
• Vite
• TypeScript

可以使用下面的方式初始化：

npm create vite@latest frontend -- --template react-ts

接著：

cd frontend
npm install
npm run dev

完成之後，就會有一個基本的 React application 在 local environment 執行。

它主要負責：

• 提供 chat interface
• 上傳與 preview data
• 將 request 傳到 backend
• 顯示 Agent responses
• render 最後的 Analysis report

除非直接影響 Agent workflow，不然我們不會花太多時間在 styling 或 UI/UX 上。

Suggested Project Structure

預想中的 project structure 如下：

project/
├── backend/
│   ├── pyproject.toml
│   ├── src/
│   └── tests/
│
├── frontend/
│   ├── src/
│   ├── package.json
│   └── ...
│
└── README.md

但可能還是會有點不同，不過影響不大。之後我們會再加入 sandbox 與其他 supporting infrastructure。

Working with a Coding Agent

當 project 初始化完成之後，就可以開始讓 coding agent 幫我們開發。

一個常見的做法是直接給 Agent 一個非常大的需求，例如：

Build me an Agentic data analysis platform.

這樣做的確可能很快得到一個可以執行的 application，但中間可能有非常多的問題，要燒掉非常多的token($$$)跟時間可能還是沒辦法如預期中的使用。

下一篇開始，會從基本的資料讀取開始，展示要怎麼建立跟設計code base。